API Design Pattern of the Week 21: Service Level Agreement
A pattern from the book “Patterns of API Design: Simplifying Integration with Loosely Coupled Message Exchanges”
The first 14 patterns in the “API Design Pattern of the Week” series came as LinkedIn articles; patterns 15 to 21 as Medium stories. All 21 series members are listed and linked in this index and overview story.
Note: This online excerpt of the pattern predates its final version in the book.
Context
An API contract or an API Description have been defined for the API, including the functional interface specification (i.e., request and response messages with parameters) of the operations. However, the behavior of the API operations has not been articulated precisely yet in terms of quantitative Quality-of-Service (QoS) characteristics.
Problem
How can an API client learn about the specific Quality-of-Service (QoS) characteristics of an API and its endpoint operations? How can these characteristics, and the consequences of not meeting them, be defined and communicated in a measurable way?
Forces
Partially conflicting concerns make it hard to specify QoS characteristics in a way that is acceptable both for clients and providers:
- Business agility and vitality
- Attractiveness from the consumer point of view
- Availability
- Performance and scalability
- Security and privacy
- Government regulations and legal obligations
- Cost-efficiency and business risks from a provider point of view
These and other pattern forces are explained in depth in the book.
Solution Sketch
As an API product owner, establish a structured, quality-oriented Service Level Agreement that defines testable service-level objectives.
A PlantUML diagram (from pre-book times) shows a common SLA structure:
Example
Imagine a fictitious SaaS provider, offering a salary administration software including an API for a payroll service. The provider states that:
“The payroll service has a response time of maximally 0.93 seconds.”
The response time might need some clarification:
“The response time is measured from the time the request arrives at the API endpoint until the response has been fully processed.”
Note that this does not include the time it takes for the request and response to travel across the network from the provider’s API endpoint to the client’s endpoint. Furthermore, the provider assures:
“The Payroll SLO will be met for 99% of the requests, otherwise the customer will receive a discount credit of 10% on the current billing period. To receive a credit the customer must submit a claim to our customer support center including the dates and times of the incident.”
Related Patterns
An SLA accompanies the API Description (service contract). The details of Rate Limits and Pricing Plans can be included in an SLA.
More Information
Beyer et al. (2016) devotes an entire chapter to Service Level Objectives, including measurements for them, called Service Level Indicators (SLIs). A post in the Google Cloud Platform Blog covers SLA, SLO and SLI management as well.
References
Beyer, Betsy, Chris Jones, Jennifer Petoff, and Niall Richard Murphy. 2016. Site Reliability Engineering: How Google Runs Production Systems. 1st ed. O’Reilly.
C-SIG. 2014. “Cloud Service Level Agreement Standardisation Guidelines.” Cloud Select Industry Group, Service Level Agreements Subgroup; European Commission. https://ec.europa.eu/newsroom/dae/redirection/document/6138.
Zimmermann, Olaf and Stocker, Mirko and Lübke, Daniel and Zdun, Uwe and Pautasso, Cesare. 2022. Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges, Vaughn Vernon Signature Series, Addison-Wesley Professional.
This pattern originally appeared on our website https://api-patterns.org., which collects 44 patterns in five categories: Foundation, Responsibility, Structure, Quality, Evolution.
Copyright © 2019–2023 by the authors. All rights reserved.
See terms and conditions of use.
